SuperHack/SuperHack CD.bin/CODING/SOUND/PLAY_SRC.ZIP/PLAY.DOC

Text File | 1994-11-25 | 8.6 KB | 261 lines

                     Extreme's Advanced Music System (AMS)
                     .-----------------------------------.


1.0 - Introduction
------------------

This is the player routine for our music system that let you use the AMS
modules in your own productions. You may use this as you wish as long as you
give me (Baldric of Extreme) credits for the player.
(Donations are VERY welcome)


1.1 - Programming notes.
------------------------

To be able to use this player you must code in Protected Mode, as we have no
plans to convert it to real mode. The Protected mode header we use is made
by TRAN, and the current version is 2.5. For your convenience we included the
sligthly changed version of TRAN'S header, so you can start immediately.


1.2 - Copyright notice
----------------------

This program is copyrighted 1994 by Extreme's Tracker Developing Team and
may not be distributed in any other form than the evaluation version,
providing that the following rules are respected.

   * Modifications in any of the distributed .OBJ files and documents
     are strictly prohibited!
   * The distributor may only charge a fee up to the costs of the public
     domain disk and/or the postage fee.
   * On request of the author, the distributor agrees to stop distrubuting
     the program and data involved.
   * Disassembling, decompiling, re-sourcing or otherwise reverse
     engineering the program is not allowed.

By copying, distrubuting and/or using the program you indicate your
acceptance of the above rules.

1.3 - Disclaimer
----------------

There is no warranty for the program, to the extent permitted by applicable
law. Except when otherwise stated in writing the copyright holders and/or
other parties provide the program "as is" without warranty of any kind,
either expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. The
entire risk as to the quality and performance of the program is with you.
Should the program prove defective, you assume the cost of all necessary
servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will
any copyright holder, or any other party who may redistribute the program
as permitted above, be liable to you for damages, including any general,
special, incidental or consequential damages arising out of the use or
inability to use the program (including but not limited to loss of data or
data being rendered inaccurate or losses sustained by you or third parties
or a failure of the program to operate with any other programs), even if
such holder or other party has been advised of the possibility of such
damages.


2.0 - Functions
---------------

The following variables are available in the system at the moment:

──────────────────────┬─────────────────────────────────────────────────────────
   PositionJump       │
──────────────────────┘

   Set this to a proper position whenever you want to jump in the music.


──────────────────────┬─────────────────────────────────────────────────────────
   LoadOffset         │
──────────────────────┘

   See explanation below


──────────────────────┬─────────────────────────────────────────────────────────
   OwnMemory          │
──────────────────────┘

   See explanation below

──────────────────────┬─────────────────────────────────────────────────────────
   DMAPlay_Chan       │
──────────────────────┘
   Set this to 1 or 3 depending on which DMA channel you prefer.
   Set to 0 if you don't want DMA transfer.
   Must be initialized BEFORE calling AMS_Init

──────────────────────┬─────────────────────────────────────────────────────────
   GF1IRQ             │
──────────────────────┘
   Set this to 2,3,5,7,11,12 or 15 depending on which IRQ you prefer.
   Must be initialized BEFORE calling AMS_Init



The following routines are available in the system at the moment:

──────────────────────┬─────────────────────────────────────────────────────────
   AMS_Init           │
──────────────────────┘

   Calls:   None/OwnMemory
   Does:    Inits the music system, allocates memory, find GUS, etc.
            If you need your own memory in your code you MUST use the variable
            "OwnMemory" instead of Tran's allocation routines. That's because
            the player routine uses all memory it can get. You can only use the
            variable BEFORE calling AMS_Init, and therefore you can only
            allocate once, but that should be no problem.

   Example:
            mov         OwnMemory,100000        ;Get 100000 bytes for your code
            call        AMS_Init                ;Init, Address to own mem is in
                                                ;the Variable OwnMemory

            mov         edi,OwnMemory           ;Erase own memory
            mov         ecx,100000/4
            xor         eax,eax
            rep         stosd


──────────────────────┬─────────────────────────────────────────────────────────
   AMS_ReadCommandLine│
──────────────────────┘

   Calls:   None
   Does:    Read the CommandLine and put the result in the string "Modname"
            This string is 100 bytes long.

   Example:
            Call        AMS_ReadCommandLine

──────────────────────┬─────────────────────────────────────────────────────────
   AMS_LoadModule     │
──────────────────────┘

   Calls:   None/LoadOffset
   Does:    Loads the Module found in string "Modname" into memory.
            If the variable LoadOffset is set to an offset, the loader will
            skip to that offset before reading the module. That way you can
            have the module copied onto the EXE file and load the mod from
            the end of the EXE file.

   Example:
            Call        AMS_LoadModule

──────────────────────┬─────────────────────────────────────────────────────────
   AMS_StartModule    │
──────────────────────┘
   Calls:   None
   Does:    Start the playing of the current loaded module.

   Example:
            Call        AMS_StartModule

──────────────────────┬─────────────────────────────────────────────────────────
   AMS_StopModule     │
──────────────────────┘
   Calls:   None
   Does:    Stops the playing of the current playing module.

   Example:
            Call        AMS_StopModule


──────────────────────┬─────────────────────────────────────────────────────────
   AMS_ShutDown       │
──────────────────────┘
   Calls:   None
   Does:    Resets the musicsystem and eveything else needed.
            Should only be used just before quitting the program.

   Example:
            Call        AMS_ShutDown



2.1 - Error Handler
-------------------
 If some error occurs in the AMS_ routines, the procedure called
 "AMS_ErrorHandler" gets control over the situation, and it's up to you to
 correct the error by displaying a error message or whatever is needed.

 When the errorhandler gets control, ESI points to a text describing the error
 and EBX contains an error number. The following table explains EBX:
 (It may be odd to not have all numbers represented, but in the tracker more
  errors are available, and I just removed the unnecessary ones)

EBX    Explanation
──────────────────────
02h    Extremely low base mem
04h    Extremely low high mem
0ah    Not enough High memory
10h    Not enough GUS memory
11h    Error opening file
12h    Error seeking in file
13h    Error reading in file
14h    No loadable module
15h    Bad AMS Version
16h    Error creating file
17h    Error Writing file
18h    Error Closing file
19h    Error determining size of file
1ah    Error deleting file
1eh    IRQ Timeout
1fh    No GUS Found



3.0 - Problems?
---------------

If you encounter any problems, feel free to contact Baldric. (preferably
by E-Mail)

Baldric (Patrik Oscarsson)
   Bondstorps Wärdshus
      562 91 Månsarp
          Sweden

  Voice: [phone]
  E-Mail: [e-mail]


3.1 - Credits
-------------

The Music System is developed and coded by Baldric of Extreme.
The Protected mode header is made by Tran (Thomas Pytel)



3.2 - Last notes
----------------

* This small system was made in quite a hurry, so there may be some bug in it,
  even if I haven't found any.

* The loader only recognizes AMS and MOD formats even if the player supports
  S3M and STM as well.

* Why so many .OBJ files??

  pmode    -  The main Protected mode header
  io       -  Input/Output routines for Pmode
  ams      -  The Music System.
  amsshell -  A shell to communicate with the Music System.
  play     -  The player.